Skip to main content

​
Agent API Reference

The Agent class is the primary building block of BindAI. Agents encapsulate AI behavior by combining a language model, prompts, tools, memory, knowledge, and execution settings into a reusable runtime component. This page documents the public Agent API.

​
Overview

An Agent is responsible for:
  • receiving user input
  • building prompts
  • invoking language models
  • calling tools
  • accessing memory
  • retrieving knowledge
  • returning structured results
Conceptually:

​
Creating an Agent

Agents can be created programmatically or loaded from configuration files. Example:
or

​
Public Methods

​
run()

Executes the agent and returns the complete response. Example:

​
Returns

An AgentResult containing:
  • success state
  • output
  • error (if any)

​
stream()

Streams the generated response incrementally. Example:
Streaming is recommended for chat interfaces.

​
from_yaml()

Creates an agent from a YAML configuration file. Example:
This is the recommended approach for production applications.

​
Configuration

Agents typically contain:
  • name
  • description
  • provider
  • model
  • system prompt
  • user prompt
  • tools
  • memory
  • knowledge
  • execution options
These values may be configured programmatically or through YAML.

​
Language Model

Every agent uses a language model. Conceptually:
Supported providers depend on the installed BindAI provider packages.

​
Prompts

Agents support multiple prompt types. Examples include:
  • system prompt
  • developer prompt
  • user prompt
These prompts are combined before model execution.

​
Tools

Agents may invoke registered tools during reasoning.
Tools extend the capabilities of language models by allowing interaction with external systems.

​
Memory

Agents may use conversation memory.
Memory enables context-aware conversations across multiple interactions.

​
Knowledge

Agents may retrieve external knowledge before generating a response.
Knowledge retrieval allows responses to be grounded in project-specific information.

​
Results

Agent execution returns an AgentResult. Typical properties include:

​
Error Handling

Execution errors are captured inside the result object. Typical errors include:
  • provider failures
  • invalid configuration
  • unavailable tools
  • timeout
  • model errors
Applications should always inspect the result before using the output.

​
Streaming vs Run

Choose the method that best fits your application.

​
Best Practices

  • Load agents from YAML whenever possible.
  • Give every agent a clear responsibility.
  • Register only the tools required by that agent.
  • Keep prompts concise and focused.
  • Use memory only when conversational context is needed.
  • Attach knowledge sources only when retrieval is required.
  • Validate AgentResult.success before using the output.

​
Related APIs

The Agent API works closely with:
  • Project
  • Workflow
  • Tool
  • Memory
  • Provider
These APIs together form the core BindAI runtime.

​
Summary

The Agent class is the central execution component of BindAI. It combines prompts, models, tools, memory, and knowledge into a reusable AI service capable of executing requests, streaming responses, participating in workflows, and serving as the foundation for BindAI applications.